Disposing of a Format Object for a Page in a Document(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Using Format Objects and Collection Items to Format Pages

Disposing of a Format Object for a Page in a Document
You need to dispose of a format object when a user wants to modify a format for a single page that is also shared by other pages in the same document, the user wants to return to the default format, or the user decides not to save a format.
For example, a user may have a four-page document that consists of two pages in landscape orientation (pages 2 and 3) and two pages that use the default format (pages 1 and 4). A user may decide to modify the scaling of page 3 of this document. A user specifies scaling for a page in the Custom Page Setup dialog box. Note that a user also can modify scaling for the default format in the Page Setup dialog box.
When the user clicks on page 3, specifies a scaling factor, and chooses the Format button in the Custom Page Setup dialog box, you need to dispose of the format object for this page and create a new one. This user is not modifying page 2, and therefore, you should not modify or dispose of its format object.
Figure 3-16 shows a four-page document in which the second and third pages use landscape orientation, but page 3 uses a modified scaling factor. Pages 1 and 4 use the default format.
Figure 3-16 A four-page document in which pages 2 and 3 use unique formats objects

Listing 3-11 shows how to dispose of a format object for a page in a document. In this example, you need to dispose of the format object because it is shared by another page in the document (its owner count is greater than 1).
The GXDisposeFormat function decrements the owner count of this format object by 1. In this example, the format object is now used by only one page in the document, so its owner count becomes 1. Storage for a format object is removed only when its owner count becomes 0. After you call the GXDisposeFormat function, you need to call the GXNewFormat function to create a new format object for this page.
Listing 3-11 Disposing of a format object for a page in a document and creating a new one
OSErr MyDeletePage(MyDocumentPtr myDocument)
{  
   OSErr    err;
   long     curPage, pg;

   /* 
      Dispose of the current page's shape object and format
      object. 
   */
   curPage = myDocument->curPage;
   GXDisposeShape(myDocument->documentPage[curPage -1]);
   if (myDocument->pageFormat[curPage -1] != nil)
      GXDisposeFormat(myDocument->pageFormat[curPage -1]);

   /* Place application-specific code to delete a page here. */
   ...

   /*
      Shift all pages coming after this one to fill the gap
      created by this deletion.  When finished, decrement the
      number of pages in the document.
   */
   if (myDocument->numPages != 0)
      for (pg = curPage; pg < myDocument->numPages; pg++)
      {
         myDocument->documentPage[pg -1] = 
                                    myDocument->documentPage[pg];
         myDocument->pageFormat[pg -1] = 
                                    myDocument->pageFormat[pg];
      }
   --myDocument->numPages;

   /* If the current page is beyond the last page, reset it. */
   if (curPage > myDocument->numPages)
      --myDocument->curPage;

   /* 
      Invalidate the window so that the page is updated on screen. 
      Check for errors and return.
   */
   InvalRect(&(myDocument->documentWindow)->portRect);
   err = GXGetJobError(myDocument->documentJob);
   if (err == noErr) err = (OSErr)GXGetGraphicsError(nil);
   return err;
}